@...SAY...GET

    To display and input data at specified row and column positions.

Syntax

    @ <exp N1>, <exp N2> [SAY <exp> [PICTURE <clause>]] [GET <variable>
    [PICTURE <exp C>] [RANGE <exp N1>,<exp N2>] [VALID <expL>]

Arguments

    <exp N1> is the row coordinate.

    <exp N2> is the column coordinate.

Options

    Say: The SAY clause displays the result of an <exp> of any type
    (including a memo field) at the specified coordinates on the current
    DEVICE.  Clipper supports two devices: PRINT and SCREEN.  If DEVICE is
    SET TO PRINT. output is directed to the printer.  Otherwise it is
    directed to the SCREEN.  To direct @...SAYS to a file, SET DEVICE TO
    PRINT and then SET PRINTER TO <output filename>.  Output destined for
    the printer is then redirected to the specified text file.

    @...SAYs to the printer behave a little differently than to the screen.
    If you address a printer row and column position less than the last
    position printed since an EJECT or SETPRC(), Clipper performs an EJECT
    and resets the internal PROW() and PCOL() values.  Your printing logic
    must, therefore, proceed sequentially from left to right down the page.

    SAYs display in standard color (see SET COLOR).

    Get: The GET clause displays a <variable> (a field or memory
    variable) at a specified screen coordinate and adds it to the list of
    pending GETs.  A subsequent READ invokes a full-screen edit mode
    allowing you to edit the contents of the pending GETs with a full
    complement of editing and navigation keys.  For a complete list of
    keys, see READ.

    Clipper supports GETting fields from other work areas if fields are
    referenced using the alias.

    GETs display in enhanced color unless there is an unselected COLOR
    SETting.  if this is the case, the current GET displays in the enhanced
    color and all other active GETs display in the unselected color.

    Note that GETs are not directed to the printer or a file with SET
    DEVICE TO PRINT.

    Picture: The PICTURE clause defines the mask for entry into a GET
    and formats the output of a SAY.  Clipper provides two mechanisms to
    control formatting: function and/or a template.  Functions
    apply to the entire SAY or GET while templates mask characters position
    by position.

    Functions: A PICTURE function is a symbol preceded by an "@."  If a
    template symbol follows the function, it must be preceded with a space.
    Note that more than one function can be applied within the same
    PICTURE.  The following table summarizes the available functions:

PICTURE FUNCTIONS

    Func  Type   Description

     A     C     Allows only alphabetic characters into a GET
     B     N     Displays numbers left-justified
     C     N     Displays CR (credit) after positive numbers
     D     D,N   Displays dates in SET DATE format
     E     D,N   Displays dates in British format, numerics in European
                 format (command and period reversed)
     K     ALL   Clears GET if first key is not a cursor key
     R     C     Non-template characters are inserted
    S<n>   C     Allows horizontal scrolling within a GET
     X     N     Displays DB (debit) after negative numbers
     Z     N     Displays zeros as blanks
     (     N     Encloses negative numbers in parentheses w/ leading spaces
     )     N     Encloses negative numbers in parentheses w/o leading spaces
     !     C     Converts alphabetic characters to upper case

    Templates: Template symbols follow functions in the PICTURE string
    if they are specified.  Each position in the output or input stream is
    mapped to the symbol in the same position in the template.  Clipper
    provides a number of template symbols as follows:

    Template    Description

       A        Displays only alphabetic characters
       N        Displays only alphabetic and numeric characters
       X        Displays any character
       9        Displays digits for any data type with sign for numerics
       #        Displays digits, signs, and spaces for any data type
       L        Displays logicals as "T" or "F"
       Y        Allows only "Y" or "N"
       !        Converts an alphabetic character to upper case
       $        Displays a dollar sign in place of a leading space in a
                numeric
       *        Displays an asterisk in place of a leading space in a
                numeric
       .        Specifies a decimal point position.
       ,        Specifies a comma position.

    Other characters specified in the template overwrite the character at
    the same position in the source stream and output.  If, however, you
    use the "R" function, non-template symbols specified are inserted into
    the display but not output if the PICTURE applies to a GET.

    Range: The RANGE clause limits entry into date and numeric type
    variables by specifying the lower and upper bounds of acceptable input
    (the lower must precede the upper).  If the value is not within the
    RANGE, an indicating message displays in the SCOREBOARD area and
    control returns to the GET.  Note that the RANGE check is performed
    unless you press Esc to terminate the GET.  In this case, there is no
    RANGE check and the <variable> is restored to its original value.

    Value: The VALID clause allows you the validate an entry into a GET
    with a logical expression.  Like RANGE, the VALID expression evaluates
    whenever you attempt to terminate the associated GET unless you press
    Esc and ESCAPE is ON.  If the expression returns false (.F.) control
    returns to the GET and you cannot leave the GET until the expression
    returns true (.T.) or you press Esc.

    Note that the expression may contain or be a user-defined function.
    This is useful for lookups and other types of post-processing
    functions.  One of the unique capabilities of Clipper is that within a
    user-defined function called by VALID, you can change the contents of
    the current GET.  You do this simply by STOREing or REPLACEing a new
    value into the current GET variable.  When control returns to the GET,
    Clipper updates it with the new value of the variable.

Usage

    Help: You can create a help system that operates within a screen
    consisting of @...SAY...GETs by first SETting KEY TO a specific help
    procedure.  Then within the procedure, use READVAR() to determine the
    current GET and display the appropriate help screen.  Note that within
    a SET KEY procedure, you can change the contents of the current GET in
    the same way you would from within a VALID.